home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / misc / libx11inc.lha / X11 / Wc / MapAg.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-02-13  |  7.6 KB  |  214 lines
  1. #ifndef _MapAg_h_
  2. #define _MapAg_h_
  3. #include <X11/Wc/COPY>
  4.  
  5. /*
  6. * SCCS_data: @(#) MapAg.h 1.6 92/06/10 06:11:07
  7. *
  8. * Mapping Agent - MapAg.h
  9. *
  10. * This include file describes an agent for associating arbitrary data.  In all
  11. * cases, the data consists of char* (pointers to anything).
  12. *
  13. * An adaptative hashing algorithm is used: when multiple collisions occur,
  14. * an attempt is made to modify the hashing algorithm to reduce collisions.
  15. *
  16. * Functional Interface:
  17. *
  18. *    MapAg_New()    Create a new mapping agent
  19. *    MapAg_Free()    Destroy an existing map database.
  20. *
  21. *    MapAg_Define()    Set mapping of (a,b,c) to data - replaces any 
  22. *            existing mapping of (a,b,c) to anything.
  23. *    MapAg_Find()    Find data associated with (a,b,c).
  24. *    MapAg_FindMap()    Find Map which associates with (a,b,c).
  25. *    MapAg_Forget()    Forget association from (a,b,c) to anything.
  26. *
  27. * All but the contructor (MapAg_New()) exist as macros and as actual functions.
  28. * The functions perform sanity checks on the agent before invoking the methods.
  29. * Otherwise, the functions do exactly the same thing as the macros.  One should
  30. * use the macros unless core dumps occur very near to agent method invocations.
  31. *
  32. * A mapping agent can also be statically declared using the MapAg_STATIC macro:
  33. *
  34. *    static MapAgReg fooAgentRec = MapAg_STATIC;
  35. *    static MapAg    fooAgent    = &fooAgentRec;
  36. *
  37. *******************************************************************************
  38. */
  39.  
  40. #include <stdio.h>
  41.  
  42. #ifndef NeedFunctionPrototypes
  43. #if defined(FUNCPROTO) || defined(__STDC__) || defined(__cplusplus) || defined(c_plusplus)
  44. #define NeedFunctionPrototypes 1
  45. #else
  46. #define NeedFunctionPrototypes 0
  47. #endif /* __STDC__ */
  48. #endif /* NeedFunctionPrototypes */
  49.  
  50. /* Macro for ANSI or K&R external declarations.  Declare them like this:
  51. **    int foo _(( int bar, MapAg glorp ));
  52. */
  53. #ifndef _
  54. #if NeedFunctionPrototypes
  55. #define _(a) a        /* ANSI results in: int foo ( int bar, MapAg glorp ); */
  56. #else
  57. #define _(a) ()        /* K&R  results in: int foo ();                  */
  58. #endif
  59. #endif
  60.  
  61. /*  -- MapAg Method Type Declarations
  62. *******************************************************************************
  63.     Integer return values are 1 if failure, 0 if OK.
  64. */
  65. typedef struct _MapAgRec* MapAg;
  66. typedef struct _MapRec*   Map;
  67.  
  68. typedef void  (*DefineMethod)    _(( MapAg, char*, char*, char*, char* ));
  69. typedef char* (*FindMethod)    _(( MapAg, char*, char*, char* ));
  70. typedef Map   (*FindMapMethod)    _(( MapAg, char*, char*, char* ));
  71. typedef void  (*ForgetMethod)    _(( MapAg, char*, char*, char* ));
  72. typedef void  (*FreeMethod)    _(( MapAg ));
  73. typedef void  (*ResizeMethod)    _(( MapAg ));
  74.  
  75. /*  -- Map and MapAg Object Declarations
  76. *******************************************************************************
  77. */
  78. typedef struct _MapRec    {    /* Stores one entry. */
  79.     char*         a;
  80.     char*        b;
  81.     char*        c;
  82.     char*        data;
  83.     struct _MapRec*    next;
  84. } MapRec;
  85.  
  86. typedef struct _MapAgRec {    /* Stores hash table for mapping.    */
  87.     Map*        table;    /* Pointer to hash table of Maps.    */
  88.     int            mask;    /* Current size of hash table minus 1.    */
  89.     int            numMaps;/* Maps currently in hash table.    */
  90.     int            shiftA;    /* used by Hash: num insig LSBs in `a'    */
  91.     int            shiftB;    /* used by Hash: num insig LSBs in `b'    */
  92.     int            shiftC;    /* used by Hash: num insig LSBs in `c'    */
  93.     DefineMethod    Define;    /* Add/change the data mapped to a,b,c    */
  94.     FindMethod        Find;    /* find data mapped to a,b,c        */
  95.     FindMapMethod    FindMap;/* find Map which maps a,b,c        */
  96.     ForgetMethod    Forget;    /* forget any mapping of a,b,c        */
  97.     FreeMethod        Free;    /* Free a MapAg and all its mappings    */
  98.     ResizeMethod    Resize;    /* PRIVATE resize table method         */
  99. } MapAgRec;
  100.  
  101. /* -- MapAg Class Methods
  102. *******************************************************************************
  103. */
  104. extern MapAg    MapAg_New();    /* allocate and initialize a new agent */
  105. extern void    MapAg_AssertLooksOk _(( MapAg, char*, int ));
  106. /* usage:    MapAg_AssertLooksOk( agent, __FILE__, __LINE__ );    */
  107.  
  108. /*  -- MapAg Instance Methods
  109. *******************************************************************************
  110.     The following macros should be used to invoke methods of Mapping Agents.
  111.     The assertions are disabled by defining NDEBUG (see assert(3)).
  112.  
  113.     If they were actually implemented in C, the functions would be:
  114.  
  115.     void  MapAg_Define  _(( MapAg, char* a, char* b, char* c, char* data ));
  116.     char* MapAg_Find    _(( MapAg, char* a, char* b, char* c ));
  117.     Map   MapAg_FindMap _(( MapAg, char* a, char* b, char* c ));
  118.     void  MapAg_Forget  _(( MapAg, char* a, char* b, char* c ));
  119.     void  MapAg_Free    _(( MapAg ));
  120.  
  121.     Note that these macros cast all arguments to char* so the client does not
  122.     need to.  Therefore, do NOT assume that the data is anything but a pointer!
  123.  
  124.     Note that the agent argument is used twice!  Don't use side effects!!
  125. */
  126.  
  127. #ifdef NDEBUG
  128. #define MapAg_Define(ag,a,b,c,d) \
  129.     ((ag)->Define((ag),(char*)(a),(char*)(b),(char*)(c),(char*)(d)))
  130.  
  131. #define MapAg_Find(ag,a,b,c)    \
  132.     ((ag)->Find((ag),(char*)(a),(char*)(b),(char*)(c)))
  133.  
  134. #define MapAg_FindMap(ag,a,b,c) \
  135.     ((ag)->FindMap((ag),(char*)(a),(char*)(b),(char*)(c)))
  136.  
  137. #define MapAg_Forget(ag,a,b,c)    \
  138.     ((ag)->Forget((ag),(char*)(a),(char*)(b),(char*)(c)))
  139.  
  140. #define MapAg_Free(ag)    ((ag)->Free(ag))
  141.  
  142. #else
  143. #define MapAg_Define(ag,a,b,c,d)                \
  144.     (MapAg_AssertLooksOk((ag),__FILE__,__LINE__),        \
  145.     (ag)->Define((ag),(char*)(a),(char*)(b),(char*)(c),(char*)(d)))
  146.  
  147. #define MapAg_Find(ag,a,b,c)                    \
  148.     (MapAg_AssertLooksOk((ag),__FILE__,__LINE__),        \
  149.     (ag)->Find((ag),(char*)(a),(char*)(b),(char*)(c)))
  150.  
  151. #define MapAg_FindMap(ag,a,b,c)                    \
  152.     (MapAg_AssertLooksOk((ag),__FILE__,__LINE__),        \
  153.     (ag)->FindMap((ag),(char*)(a),(char*)(b),(char*)(c)))
  154.  
  155. #define MapAg_Forget(ag,a,b,c)                    \
  156.     (MapAg_AssertLooksOk((ag),__FILE__,__LINE__),        \
  157.     (ag)->Forget((ag),(char*)(a),(char*)(b),(char*)(c)))
  158.  
  159. #define MapAg_Free(ag)                        \
  160.     (MapAg_AssertLooksOk((ag),__FILE__,__LINE__),        \
  161.     (ag)->Free(ag))
  162.  
  163. #endif
  164.  
  165. /*  -- Variable Method Declarations
  166. *******************************************************************************
  167.     **** NEVER REFERENCE ANY OF THESE FUNCTIONS!! ****
  168.     They are only declared here so the MapAg_STATIC macro can be defined.
  169.  
  170.     All integer return values reflect failure if non-zero.
  171. */
  172.  
  173. void  MapAg_Define_Initial    _(( MapAg, char*, char*, char*, char* ));
  174. void  MapAg_Define_Normal     _(( MapAg, char*, char*, char*, char* ));
  175.  
  176. char* MapAg_Find_Initial    _(( MapAg, char*, char*, char* ));
  177. char* MapAg_Find_Normal        _(( MapAg, char*, char*, char* ));
  178.  
  179. Map   MapAg_FindMap_Initial    _(( MapAg, char*, char*, char* ));
  180. Map   MapAg_FindMap_Normal    _(( MapAg, char*, char*, char* ));
  181.  
  182. void  MapAg_Forget_Initial    _(( MapAg, char*, char*, char* ));
  183. void  MapAg_Forget_Normal    _(( MapAg, char*, char*, char* ));
  184.  
  185. void  MapAg_Free_Dynamic    _(( MapAg ));
  186. void  MapAg_Free_Static        _(( MapAg ));
  187.  
  188. void  MapAg_Resize_Initial    _(( MapAg ));
  189. void  MapAg_Resize_Normal    _(( MapAg ));
  190.  
  191. /*  -- Macro to allow mapping agents to be statically declared
  192. *******************************************************************************
  193.     This macro must be coordinated with MapAg_New() so they both do
  194.     the same type of initialization.  Static agents have a different
  195.     free method, of course.
  196. */
  197.  
  198. #define MapAg_STATIC { \
  199.     /* newAgent->table     */ (Map*)0,            \
  200.     /* newAgent->mask     */ (int)0,            \
  201.     /* newAgent->numMaps */ (int)0,            \
  202.     /* newAgent->shiftA  */ (int)0,            \
  203.     /* newAgent->shiftB  */ (int)0,            \
  204.     /* newAgent->shiftC  */ (int)0,            \
  205.     /* newAgent->Define     */ MapAg_Define_Initial,    \
  206.     /* newAgent->Find     */ MapAg_Find_Initial,        \
  207.     /* newAgent->FindMap */ MapAg_FindMap_Initial,    \
  208.     /* newAgent->Forget     */ MapAg_Forget_Initial,    \
  209.     /* newAgent->Free     */ MapAg_Free_Static,        \
  210.     /* newAgent->Resize     */ MapAg_Resize_Initial    \
  211. }
  212.  
  213. #endif /* _MapAg_h_ */
  214.